Plan

  1. Avant-propos

  2. Organisation et généralités

  3. Les exigences

  4. SysML

  5. Exigences et tests

  6. Traçabilité

  7. Génération de doc

Avant-propos

Dilbert
Figure 1. Produire des applications

Nous allons nous intéresser dans ce cours aux Méthodologies de la Production d'Application.

Ce module, qui fait suite aux modules de programmation (M2103), conception (M2104) et d’IHM (M2105), est fortement corrélé au module de conception avancé (M3105).

Avant-propos (suite)

Note

Nous suivons (comme tous les DUT informatique) le programme pédagogique national (PPN - disponible ici).

M3301
Figure 2. Le contenu officiel

À qui est destiné ce document?

Les étudiants du DUT informatique, mes collègues enseignants qui cherchent un document de référence accessible, et …​ moi-même (pour organiser mes notes diverses)!

À qui il n’est pas destiné?

Si vous appartenez à une de ces catégories, ce document n’est pas pour vous :

  • vous cherchez un document de référence

  • vous voulez vous perfectionner

  • vous souhaitez préparer une certification Java ou UML™.

Historique

Ce document est tout nouveau (date de naissance 05/09/2014!), donc merci de votre indulgence …​

Vous trouverez en référence (cf. Bibiliographie) les ouvrages et autres documents utilisés.

Sur l’auteur

  • Professeur à l’Université de Toulouse, en poste à l’IUT de Blagnac

  • Co-fondateur de l’association SysML-France

  • Membre du comité éditorial de la revue SoSyM

  • Membre du Steering Committee de la conférence ACM/IEEE MODELS

  • Chef du département informatique de l’IUT de Blagnac 2009 à 2012

  • Responsable de l’ancien module (Analyse et Conception des Systèmes d’Information)

  • Marié à une merveilleuse femme, papa d’une merveilleuse fille

Comment lire ce document?

Ce document a été réalisé de manière à être lu de préférence dans sa version électronique (au format HTML ou PDF), ce qui permet de naviguer entre les références et les renvois interactivement, de consulter directement les documents référencés par une URL, etc.

WarningSi vous lisez la version papier de ce document, ces liens clickables ne vous servent à rien, et c’est votre punition pour avoir utilisé du papier au lieu du support électronique!

Conventions typographiques

J’ai utilisé un certain nombre de conventions personnelles pour rendre ce document le plus agréable à lire et le plus utile possible, grâce notamment à la puissance d’AsciiDoc :

  • Les références bibliographiques présentées en fin de document (cf. Bibliographie).

  • Les termes anglais (souvent incontournables) sont repérés en italique, non pas pour indiquer qu’il s’agit d’un mot anglais, mais pour indiquer au lecteur que nous employons volontairement ces termes (e.g., Package).

Conventions typographiques (suite)

Le titre des figures indique (entre parenthèses) un M pour les figures issues de Modelio, un MD pour les figures issues de MagicDraw, un P pour les figures issues de plantUML, un Py pour les figures issues de Papyrus, un R pour les figures issues de Rhapsody, un T pour les figures issues de TOPCASED, un Y pour les figures issues de yuml, et un UK pour les figures en anglais.

Pour les notes, conseils, avertissements, etc. voici la liste des pictogrammes utilisés :

Note

Les notes comme celles-ci sont utilisées pour indiquer des éléments intéressant pour la majorité des lecteurs.

Caution

Ces notes indiquent des points importants qui réclament votre attention.

Tip

Celles-ci concernent en général des points de détail et permettent "d’aller plus loin".

Note
Définition : Exemple (OMG UML v2.4.1, p. 152)

Ces notes concernent des définitions tirées de la spécification UML™ et sont donc précisément référencées.

Conventions typographiques (suite)

Note

Modélisation UML incorrecte.

Note

Modélisation UML partiellement correcte ou pouvant prêter à confusion.

Note

Modélisation UML correcte.

Pourquoi parler de "document"?

Parce que j’ignore la version que vous êtes en train de lire. À partir de l’original, plusieurs versions ont été générées grâce à AsciiDoc :

  • Une version pour le web (Moodle) au format html

  • Une version pour présentation en amphi au format présentation

  • Une version pour impression au format pdf

Utilisation et autres mentions légales

Les images qui ne sont pas libres de droit contiennent un lien vers les sites où je les ai "empruntées".

N’hésitez pas à m’envoyer vos remarques en tout genre en m’écrivant ici.

Organisation et généralités

Ce support de cours est destiné en priorité aux étudiants de l’IUT de Blagnac.

Comme déjà indiqué, ce module est fortement corrélé au module de Conception et Programmation Objet Avancées (CPOA - M3105).

Il ne concerne que la partie modélisation du cours, les autres aspects étant couverts par Jean-Michel Inglebert. Il est prévu pour 2 cours d'1h30, complété par des mises en oeuvre en TD et en TP. Cette partie du cours va principalement porter sur UML™, le langage universel de modélisation très utilisé en entreprise que vous maîtrisez déjà en partie.

Introduction

La matrice qui nous servira de "carte de base" pour placer les activités ou les modèles, sera celle-ci :

Table 1. La carte de base
RequirementsStructureComportementTransverse

Organisation

Analyse

Conception

Implémentation

Cette matrice permet de situer les différents éléments qui seront vus dans ce cours dans un cadre utile pour comparer ces éléments les uns aux autres. Je vous conseille de vous faire votre propre matrice. L’essentiel est de toujours bien se représenter les différents éléments qu’on aborde dans une carte mentale précise. Cela permet une meilleure mémorisation.

Points de vue

Dans un axe horizontal, j’ai différencié quatre grands points de vue :

  • Requirements

  • Structure

  • Comportement

  • Transverse

Points de vue (Requirements)

Requirements

Les exigences et leur prises en compte sont un éléments critique pour le succès du développement de tout système. Sans explorer l’ensemble des activités d’ingénierie système (ce qui nécessiterait tout un volume du type de Les exigences) nous insisterons ce semestre sur cet aspect.

Points de vue (Structure)

Structure

La description de l’architecture et des éléments constitutifs du système, avec les blocs, leurs relations, organisations internes, etc. constituera un point de vue important. C’est souvent la partie de modélisation qui pose le moins de problème aux débutants.

Points de vue (Comportement)

Comportement

Le comportement d’un système est du point de vue de l’utilisateur final beaucoup plus important que la structure elle-même. C’est la partie qu’il est la plus à même d’exprimer, de comprendre (vos modèles) et de valider.

Points de vue (Transverse)

Transverse

Un certains nombre de concepts sont transverses aux trois points de vue précédents. Il s’agira principalement de parler de cohérence ou de traçabilité entre les phases de développement ou entre les points de vue.

Phase de développement

Dans un axe vertical, j’ai différencié quatre grandes phases du cycle de vie du développement :

  • Organisation

  • Analyse

  • Conception

  • Implémentation

Phase de développement (Organisation)

Organisation

Une étape indépendante du type de cycle de développement envisagé (en V, agile, etc.) mais qui concerne la mise en place d’un cadre de travail qui permette un développement de qualité (outils, éditeurs, gestionnaire de version, de tâches, etc.).

Note

On pourrait rapprocher cette étape du "cycle 0" de Scrum.

Phase de développement (Analyse)

Analyse

Cette phase vise plutôt à examiner le domaine du problème. Elle se focalise sur les cahiers des charges et les exigences. L’analyse débouche sur un dossier d’analyse qui décrit les grandes lignes (cas d’utilisation, architecture principale) du système.

Phase de développement (Conception)

Conception

Cette phase vise plutôt à examiner le domaine de la solution. Elle débouche sur un dossier de conception qui décrit les détails conceptuels de la solution envisagée (structure détaillée, comportement, etc.)

Phase de développement (Implémentation)

Implémentation

Cette phase traite des développements finaux (construction ou approvisionnement en matériel, développement de codes, etc.).

Questions de révision

Note
  1. Associez les diagrammes suivants avec leurs acronymes :

    Diagramme de Paquetages

    sd

    Diagramme des Cas d’Utilisation

    dc

    Diagramme de Séquences Système

    uc

    Diagramme de Classes

    pkg

    Diagramme de Séquences

    dss

  2. Placez dans la matrice ci-dessous les différents diagrammes UML™ que vous connaissez déjà (sd, dc, uc, pkg, dss.

    RequirementsStructureComportementTransverse

    Organisation

    Analyse

    Conception

    Implémentation

Les exigences

L’ingénierie des exigences est d’une importance capitale, surtout en Ingénierie Système. En général les exigences sont exprimées par des ingénieurs dédiés à cette activité. La complexité des systèmes modernes (embarqués, communicants, critiques, …​) rendent cruciale cette analyse.

Joke
Figure 3. 300 corps de métiers sont parfois présents sur un même chantier

Les exigences (suite)

Tip
Besoins, exigences : question de vocabulaire

La difficulté de l’emploi massif de l’anglais fait qu’il existe souvent une confusion entre les termes anglais et leurs traduction française. Nous précisons donc ici notre utilisation des termes :

Requirements

Exigences, c’est à dire une fonction ou une propriété que doit satisfaire le système considéré. Par nature une exigence doit pouvoir être vérifiable. En génie logiciel on parle plus classiquement des spécifications ("spec") pour parler des contraintes à respecter pour un système. Les ingénieurs systèmes ont depuis longtemps intégré le terme d’exigences comme traduction directe de requirement.

Besoins

Il s’agit des exigences du client. En UML™ on va plus les retrouver dans les cas d’utilisation. Ils sont à l’origine des requirements tels que définis plus haut.

Les exigences (suite)

Il est important pour une exigence qu’elle ne soit pas ambiguë (contrairement au terme "en" dans la consigne exprimée par la maman dans l’illustration ci-dessous : "Ramène moi 1 bouteille de lait. S’il y a des oeufs, ramène m’en 6.").

Joke
Figure 4. Spécification ambiguë (taken from here)

Dans le cadre de la matrice qui nous sert de plan, nous somme ici :

RequirementsStructureComportementTransverse

Organisation

Analyse

Conception

Implémentation

Fondements

On abordera :

  • L’organization des Requirements

  • Les Requirements properties

  • Les Requirements links

  • Les Requirements Diagrams

  • Les considérations sur la traçabilité

  • Annotations des Requirements

  • Les Use Case Diagrams

Il n’existe pas de diagramme UML™ pour traiter des exigences en particulier. Nous allons donc nous servir dans cette partie d’un diagramme qui vient de SysML™.

SysML

Fiche d’identité

  • Date de naissance non officielle : 2001!

  • Première spécification adoptée à l’OMG™ : 19 septembre 2007

  • Version actuelle : 1.3 (12/06/2012)

  • Paternité : OMG™ / UML™ + INCOSE

  • Auteurs principaux :

    • Conrad Bock

    • Cris Kobryn

    • Sanford Friedenthal

  • Logo officiel : sysml

SysML, c’est…​

Un ensemble de 9 types de diagrammes
  • Diagrammes structuraux

    • Diagrammes de définition de blocs (bdd)

    • Diagrammes internes de blocs (ibd)

    • Diagrammes paramétriques (par)

    • Diagrammes de packages (pkg)

  • Diagrammes comportementaux

    • Diagrammes de séquence (sd)

    • Diagrammes d’activité (act)

    • Diagrammes de cas d’utilisation (uc)

    • Diagrammes d’états (stm)

  • Diagramme d’exigence (req)

SysML, c’est (suite) :

Un profil UML™

C’est à dire une extension de cette notation, un ensemble de nouveaux concepts et éléments qui sont définis à partir des éléments de base d’UML™. Un exemple : le bloc SysML™ n’est qu’une redéfinition de la classe UML™.

Une notation

Une notation de plus en plus enseignée et connue et qui servira donc de plus en plus de référence à la modélisation des systèmes.

SysML, ce n’est pas…​

Une méthode

En effet, contrairement à ce que beaucoup pensent en l’abordant, SysML™ ne propose pas de démarche particulière de développement de système. C’est à la fois sa force (votre méthode existante pourra continuer à être utilisée) comme sa faiblesse car cette absence de guide méthodologique fait souvent défaut à son utilisation.

Un outil

Nous verrons en effet que SysML™ ne fait que ce qu’on veut bien en faire. Comme tout langage il est limité dans son pouvoir d’expression, mais surtout il reste une simple notation qu’il convient d’utiliser avec des outils et des démarches associées.

Un raton laveur

C’est juste pour voir ceux qui suivent…​

Note

On ne dit pas "le SysML" mais tout simplement "SysML".

L’organisation des Requirements

Il ne s’agit pas ici de revenir sur les exigences elles-même, mais plutôt de voir comment SysML™ permet de les exprimer, de les manipuler et surtout de les lier avec le reste du système.

Représentation de base

Un Requirement en SysML™ n’est qu’un bloc particulier.

Note
Définition : Requirements (OMG SysML v1.3, p. 139)

A requirement specifies a capability or condition that must (or should) be satisfied…​ A requirement is defined as a stereotype of UML Class…​

corde
Figure 5. Un Requirement en SysML (P)

Différents types d’organisation

Plusieurs types d’organisations sont possibles :

  • Par niveau d’abstraction

    • Besoins généraux (en lien avec les use cases par exemple)

    • Besoins techniques (en lien avec les éléments de conception)

  • Par point de vue

    • Besoins principaux (en lien avec les use cases)

    • Besoins spécifiques :

      • Fonctionnels

      • Marketing

      • Environnementaux

      • Business

      • …​

  • etc.

Tableaux de Requirements

req table
Figure 6. Exemples tableau d’exigences (OMG SysML v1.3, p. 145)

La plupart des outils modernes permettent le passage entre outils classiques de gestion des exigences (comme DOORS™) et outils de modélisation SysML™ (comme Modelio, illustré ci-dessous).

req modelio
Figure 7. Import Modelio de tableau d’exigences (tiré de [Modelio2012])

Les Requirements properties

Il est possible d’indiquer un certain nombre de propriétés sur un requirement :

  • priority (high, low, …​)

  • source (stakeolder, law, technical, …​)

  • risk (high, low, …​)

  • status (proposed, aproved, …​)

  • verification method (analysis, tests, …​)

Note

Dans le cadre du module MPA nous ne retiendrons comme attribut d’un requirement que son identifiant et le texte le désignnat (les deux attributs obligatoire). La priorité sera donné par le client en terme de cycle (on traitera en premier les requirements prioritaires).

Ainsi en plantUML, une exigence ressemblera à ceci (cf. rendu ici):

class ObtenirHoraires <<requirement>> {
	Text = "Le logiciel doit fournir les horaires rapidement."
	Id = "14.2"
	}

Les Requirements Diagrams

Voici un exemple de req un peu plus étoffé, tiré de la norme (voir aussi Exemples de rationale et problem (tiré de SysML, UK)) :

hsuv reqs1
Figure 10. Exemples de composition d’exigences (tiré de SysML, UK)

Stéréotyper les Requirements

Tout comme pour n’importe quel bloc, il est possible de stéréotyper les requirements. Ceci permet de se définir ses propres priorités et classifications. Quelques exemples de stéréotypes utiles :

Annotations des Requirements

Il est possible d’annoter les éléments de modélisation en précisant les raisons (rationale) ou les éventuels problèmes anticipés (problem).

hsuv reqs2
Figure 11. Exemples de rationale et problem (tiré de SysML, UK)

Les considérations sur la traçabilité

Une fois que les requirements ont été définis et organisés, il est utile de les lier au moins aux use cases (en utilisant [refine] par exemple) et aux éléments structurels (en utilisant [satisfy] par exemple), mais ceci sera abordé dans la partie transverse.

Note

En général chaque requirement devrait être relié à au moins un use case (et vice-versa!).

Les Use Case Diagrams

Bien que nous traitions les cas d’utilisation dans la partie comportement, nous les abordons ici du fait de leur proximité avec les requirements.

req uc relation
Figure 12. Exemple de lien entre use case et requirements (T, UK)

Les Use Case Diagrams (suite)

Ce diagramme est celui que vous avez appris l’an dernier en UML™.

UCGestionNotes
Figure 13. Exemple de diagramme des cas d’utilisation (B)

Les Use Case Diagrams (suite)

uc
Figure 14. Autre exemple de diagrammes des cas d’utilisation (B)
Tip

Un acteur représente un rôle joué par un utilisateur humain. Il faut donc plutôt raisonner sur les rôles que sur les personnes elles-mêmes pour identifier les acteurs.

Exigences et tests

Principes

Pour ce qui ce concerne ce module nous allons nous contenter de maintenir des matrices croisant les exigences d’un côté et les tests de l’autre.

Par exemple :

matrice
Figure 15. Exemple de matrice de traçabilité

Dans la réalité, les entreprises industrialisent le processus de vérification des exigences en utilisant des outils adaptés. Illustration tirée de [TestsIndustriels2009] :

testindus
Figure 16. Le cycle de la qualification fonctionnelle en lien avec les besoins métiers

Exemple complet

En prenant un exemple tiré d’un exercice que vous avez traité l’an dernier voici un exemple cohérent :

Le texte du cahier des charges

Le texte complet de l’exemple ne précise pas le cahier des charges de l’Autoradio (AR), considérant que tout le monde sait ce que c’est!

Rédigeons tout de même quelques extraits (numérotés) de texte possible :

  1. L’AR est un dispositif qui permet d’écouter la radio de manière confortable et interactive.

  2. L’AR doit être capable de mémoriser un certain nombre de station différentes.

  3. L’Utilisateur de l’AR doit pouvoir choisir sa station parmis un choix donné.

  4. L’Utilisateur de l’AR doit pouvoir régler le niveau sonore.

  5. L’Utilisateur de l’AR doit pouvoir chercher une station en "balayant" les ondes FM.

  6. …​

Expression des exigences

Nous pouvons, en analysant ce cahier des charges, déduire un certain nombre d’exigences. Nous les écrivons ici sous forme tabulaire, et en utilisant le langage Gherkin.

Note

Concernant Gherkin, pour ceux qui veulent aller plus loin, il est possible d’automatiser la génération des tests à partir de ce genre de langage. C’est ce que fait Cucumber pour Ruby.

Expression des exigences (tabulaire)

Version tabulaire :

tabulaire
Figure 17. Exemple de liste d’exigences

Expression des exigences (Gherkin)

Exemple de version textuelle formattée (fichier source ici):

#encoding: utf-8
Feature: Scénario simple d'utilisation de l'AutoRadio (AR)
  In order to vérifier que le son marche
  As an utilisateur lambda
  I should be able to exécuter ces scénarios et constater les effets

  Scenario: Augmenter le son
    Given un AR avec le son à 0
    When Je presse le bouton "Volume +"
    Then Le son passe à 1
    And Je commence à entendre la radio

Plan de test

Créer un plan de test consiste à prévoir l’ensemble des tests à l’avance de manière à prévoir la couverture de ces tests.

plantest
Figure 18. Exemple de plan de test simplifié

Analyse et la conception

Dans un cycle classique ("en V" par exemple), les modèles sont réalisés avant l’implémentation (codage).

Dans un cycle Agile, chaque cycle possèdera ses modèles, eux aussi versionnés, qui eux aussi évolueront en même temps que le code.

Lien et traçabilité

Plus encore que dans les méthodes classiques, il conviendra de vérifier que code et modèles sont bien cohérents. On pourra donc :

Lien et traçabilité (suite)

Exemple de code Java commenté pour la génération automatique de diagrammes plantUML
package demo;

class Controller {}
class EmbeddedAgent {}
class PowerManager {}

/**
 * @extends Controller
 * @extends EmbeddedAgent
 * @navassoc - - 1..* PowerManager
 * @note this is a note
 */
class SetTopController implements URLStreamHandler {
  public String name;

  int authorizationLevel;
  void startUp() {}
  void shutDown() {}
  void connect() {}
}

/** @depend - friend - SetTopController */
class ChannelIterator {}

interface URLStreamHandler {
  void OpenConnection();
  void parseURL();
  void setURL();
  void toExternalForm();
}

Lien et traçabilité (suite)

doclet
Figure 19. Exemple de diagramme généré

En résumé

Les exigences sont très importantes en ingénierie logiciel, du fait de la multiplication des sous-systèmes et donc des intermédiaires (fournisseurs, sous-traitants, etc.) avec qui les aspects contractuels seront souvent basés sur ces exigences. Il n’est donc pas étonnant qu’un diagramme et des mécanismes dédiés aient été prévus en SysML™.

Table 2. Déclinaison des Exigences
RequirementsStructureComportementTransverse

Organisation

⊕–, \<<deriveReqt>>

Analyse

[satisfy], [refine]

[satisfy] entre reqs et UC

[refine]

Conception

\<<allocate>>

Implémentation

\<<satisfy>>, \<<verify>>

Les Use Case Diagrams (suite)

En terme de démarche, il est classique d’avoir de nombreux aller-retour entre la modélisation des exigences et la modélisation du système lui-même (cf. Exemple de démarche (SYSMOD Zigzag pattern)).

zigzag
Figure 20. Exemple de démarche (SYSMOD Zigzag pattern)

Concernant le projet

Questions de révision

Note
  1. Quelles sont les différences entre besoins et exigences ?

  2. Quelles sont les différences entre un backlog de produit et une exigences?

  3. En quoi les cas d’utilisation sont-ils complémentaires des exigences?

Documentations et modèles générés

  • Liens et traçabilité

  • Exemple concernant les exigences

  • Exemple concernant les classes

Liens et traçabilités

Plus encore que dans les méthodes classiques, il conviendra de vérifier que code et modèles sont bien cohérents. On pourra donc :

Exemple concernant les exigences

On part des exigences (en Scrum, le Product Backlog) :

Backlogs

Exemple concernant les exigences (suite)

On les liste dans redmine :

La liste précise

Exemple concernant les exigences (suite)

On les exporte dans un format manipulable (exemple .csv) :

Export CSV

Exemple concernant les exigences (suite)

On les passes dans une moulinette maison pour obtenir du plantUML :

Exemple de conversion en PlantUML
@startuml

class Req_2205 <<Requirements>> {
Id = 2205
Text = "En tant qu'administrateur, je veux pouvoir afficher la liste des intervenants du fichier intervenants2014_2015.csv dans l'IHM"
}

class Req_2213 <<Requirements>> {
Id = 2213
Text = "En tant qu'administrateur, je veux pouvoir afficher la liste des sujets puis ajouter un nouveau sujet et sauvegarder la liste des projets dans un fichier .csv de mon choix"
}

class Req_2220 <<Requirements>> {
Id = 2220
Text = "En tant qu'administrateur, je veux pouvoir afficher la liste des étudiants indiquant le groupe, le sujet, le projet et l'ensemble des intervenants du projet dans l'IHM"
}

...
@enduml

Exemple concernant les exigences (suite)

Le fichier complet est disponible ici. Ce qui donne le rendu ci-dessous :

Diagramme des exigences
Note

Les exemples ne sont pas des corrections du projet en cours, mais sont donnés ici uniquement à titre d’illustration.

Exemple concernant les exigences (suite)

On réalise qu’il serait nécessaire de disposer d’une API digne de ce nom pour aller directement chercher les exigences dans redmine.

Générer un diagramme de classe à partir de Java commenté

Exemple de code Java commenté pour la génération automatique de diagrammes plantUML
package demo;

class Controller {}
class EmbeddedAgent {}
class PowerManager {}

/**
 * @extends Controller
 * @extends EmbeddedAgent
 * @navassoc - - 1..* PowerManager
 * @note this is a note
 */
class SetTopController implements URLStreamHandler {
  public String name;

  int authorizationLevel;
  void startUp() {}
  void shutDown() {}
  void connect() {}
}

/** @depend - friend - SetTopController */
class ChannelIterator {}

interface URLStreamHandler {
  void OpenConnection();
  void parseURL();
  void setURL();
  void toExternalForm();
}

Générer un diagramme de classe (suite)

doclet

Générer de l’asciidoc par javadoc

Pour aller un cran plus loin, vous pouvez même envisager de d’intégrer de l’AsciiDoc au moment de générer la documentation avec Javadoc!

asciidoclet diagram example
Tip

Pour plus d’info : Asciidoclet

Générer de l’asciidoc par javadoc (suite)

On peut même utiliser la puissance des variables. Par exemple les commentaires Java suivants seront mis à jour en ajoutant les options suivantes au doclet :

-a product-name=OPTI -a version=1.0
/**
 * {product-name} will change your life!
 * @version {version}
 */
Tip

Cette astuce est aussi valable en AsciiDoc!

Tester la génération de doc

À partir du moment où la documentation est générée, on peut tester le programme qui la génère, comme n’importe quel programme.

Dans les exemples qui suivent on peut :

  • tester l’existence des fichiers qui sont inclus (e.g., include::foo.txt[])

  • tester la conformité avec les règles définies dans le sujet

  • tester la conformité aux bonnes pratiques

Les fichiers inclus existent-ils bien?

En utilisant un simple script Ruby (facilement intégrable en CI avec Travis par exemple) voici ce qu’on obtient :

checkImages note

Les fichiers inclus existent-ils bien? (suite)

Voici le détail du script :

# CheckImage.rb
# 2014 -- JMB (initial code from JM Inglebert)
#----------------------------------------------------
re = Regexp.new("\.html$") # asciidoc result file (easier!)

dir = Dir.new('.')
dir.each  {|fn|
    if ( fn =~ re ) then
        print "asciidoc source : " + fn + "\n"
        paths = []
        # find all image: or image:: asciidoc macros
        File.open(fn) { |f|
          p 'opening ' << fn
            content = f.read
            paths = content.scan(/<img src="([^"]*)"/)
        }
        imagesDir='/Users/bruel/dev/Papyrus4Education/images'
        # test that path is a file
        paths.flatten.each {|path|
            print (File.file?(path) ? " OK " : " NOK ") + path + "\n"
        }
    end
}

Règles sur le contenu

On peut vérifier plusieurs aspects d’un document :

  • Que le contenu est conforme aux attentes

  • Que les bonnes pratiques ont été appliquées

Contenu conforme aux attentes

Le cahier des charges (http://algec.iut-blagnac.fr/~jmi/MPA/sprint_0.html) mentionne :

La documentation utilisateur devra fournir les informations suivantes :

- liste des membres de l'équipe et numéro de groupe
- Université Toulouse 2
- IUT de Blagnac
...

Contenu conforme aux attentes (suite)

Voilà un exemple de script de test pour ces règles.

#La documentation utilisateur devra fournir les informations suivantes :

file = ARGV[0]
membre = Regexp.new(ARGV[1])
groupe = Regexp.new(ARGV[2])
sprint = Regexp.new(ARGV[3])


f = File.open(file)
content = f.read

# liste des membres de l'équipe

res = content.scan(membre)
print "Membre : " + (res != [] ? " OK " : " NOK ") + "\n"

# numéro du groupe

res = content.scan(groupe)
print "Groupe : " + (res != [] ? " OK " : " NOK ") + "\n"

# Université Toulouse 2

res = content.scan(Regexp.new("Université Toulouse 2"))
print "UT2 : " + (res != [] ? " OK " : " NOK ") + "\n"

Contenu conforme aux attentes (suite)

# IUT de Blagnac

res = content.scan(Regexp.new("IUT de Blagnac"))
print "IUT : " + (res != [] ? " OK " : " NOK ") + "\n"

# DUT INFO S3/Module MPA

res = content.scan(Regexp.new("DUT INFO S3/Module MPA"))
print "MPA : " + (res != [] ? " OK " : " NOK ") + "\n"

# le nom du projet : OPTI

res = content.scan(Regexp.new("OPTI"))
print "OPTI : " + (res != [] ? " OK " : " NOK ") + "\n"

# le SPRINT concerné

res = content.scan(Regexp.new(sprint))
print "SPRINT : " + (res != [] ? " OK " : " NOK ") + "\n"

Contenu conforme aux attentes (suite)

Ce qui donne :

checkDoc

Règles sur les bonnes pratiques

Papyrus doc

Règles sur les bonnes pratiques

Voici un exemple qui vérifie que la documentation est conforme aux règles Eclipse Doc Style Guide.

Par exemple la Eclipse Doc Style Guide préconise :

Use sentence capitalization for all titles.

Règles sur les bonnes pratiques

Voilà le script de test pour cette règle.

#require 'minitest/spec'
require 'minitest/autorun'

#---------------------------------------------------
# Checking Titles
#---------------------------------------------------
    MAIN='main.wiki'
    File.open(MAIN) { |f|
          content = f.read
          titles = content.scan(/=+ (.*) =+/)
          # test that titles have Capital first letter
          titles.flatten.each {|title|
            describe File do
              it "Wiki should use sentence capitalization for all titles" do
                assert_match(/[A-Z].+$/, title)
              end
            end
          }
        }

Règles sur les bonnes pratiques

Et le résultat :

checkTitles note
Note

Bien sûr tout n’est pas testable. Exemple de règle difficile à instrumenter : "Wherever possible, make statements positive."

"Asciidoc ne marche pas sur ma machine!"

Tip

Alors utiliser l’intégration continue ([CI]) et la virtualisation!

Nous allons détailler l’exemple d’un cas concret :

framework

[0] Le client fournit les templates, CSS stylesheets, …​

Hors de propos, mais en tant que programmeur, c’est très pratique.

StylesheetsDefinition
Note

Vous n’auriez pas en avoir bénéficié en MPA?

[1] Les contributeurs fournissent les inputs, en s’occupant du contenu

De la même façon que vous avez conçus vos fichiers sources AsciiDoc.

[2] Tout est versionné et contrôlé

Dans notre exemple, nous utilisons GitHub.

[3] Travis est utilisé pour lancer les tests et générer les outputs

Cf. détails sur la configuration ci-après.

[4] Le résultat est disponible sur le web sur de multiples formats

Les formats courants sont supportés :

  • PDF

  • ebook

  • HTML

  • Slides (Deck.js, Reveal.js, slidy2, …​)

  • Docx

  • …​

Configuration

Le but de ces notes est d’expliquer le fonctionnement de la génération de document HTML par intégration continue en utilisant Travis en complément des dépôts GitHub.

La démarche globale (cf. [figure]):

  1. Se connecter à Travis avec ses identifiants GitHub.

  2. Configurer les dépôts à "intégrer" de manière continue

  3. Ajouter un fichier .travis.yml à la racine du dépôt (penser à l’ajouter : git add)

  4. Lors du git push (après un git commit bien sûr), Travis va générer une machine virtuelle qui va exécuter le script et indiquer un succès si tout c’est bien passé.

travis

Connection entre Github et Travis

Pour ne pas avoir à préciser les mots de passe en clair dans vos scripts, il est possible d’indiquer les éléments de connexions de manière crypté. Ainsi il faut :

  1. Associer un token à votre dépôt sous GitHub (cf. explications ici).

  2. Installer Travis

    gem install travis
  3. Crypter (et ajouter au fichier .travis.yml en même temps) votre token

    travis encrypt MY_SECRET_ENV=super_secret --add env.matrix
Note

Il est possible de valider la syntaxe du fichier .travis.yml en installant un utilitaire :

gem install travis-lint
travis-lint

Exemple de fichiers

Un fichier Travis

".travis.yml"
#language: python
#python:
#- '2.7'
install:
- gem install asciidoctor
- gem install link-checker

script:
#- asciidoctor --version
#- ls -alF
#- whereis bash
- asciidoctor -a icons -a linkcss! -a numbered faq.txt -o output/faq.html
#- ls -al output
#- bash update-doc.sh
- rake check_links

# Following generated by
#
# travis login --pro
# travis encrypt -r jmbruel/PapyrusFAQ GH_TOKEN=<token generated on gitHub> --add env.global
env:
  global:
    secure: cEaBJq02ObnKSWQHP0c.....WMQX8Py4icaC8Cn9l62AqE4=

# if everything OK, then deploy on the web
after_success:
- bash update-doc.sh

Un fichier de script lancé par Travis

update-doc.sh
#!/bin/bash
echo -e "Starting to update doc\n"

#copy data we're interested in to other place
cp -R output $HOME/output

#go to home and setup git
cd $HOME
git config --global user.email "jbruel#travis@gmail.com"
git config --global user.name "Jean-Michel Bruel"
git config --global push.default simple

#using token clone io pages branch
git clone --quiet https://${GH_TOKEN}@github.com/jmbruel/jmbruel.github.io.git  doc > /dev/null

#go into directory and copy data we're interested in to that directory
cd doc
cp $HOME/output/faq.html ./index.html
ls -al index.html

#add, commit and push files without provoking Continuous Integration
git add -f index.html
git commit -m "Travis build $TRAVIS_BUILD_NUMBER pushed to io pages -- [skip ci]"
git push -fq origin master > /dev/null

echo -e "Done magic with output\n"
Tip

Notez le [skip ci], qui permet d’éviter la récursivité du processus (modif du push donc relance du script!).

Branches et SVN

Il n’est pas normal de ne pas pouvoir présenter une release qui fonctionne.

Tip

Voir l’équivalent pour git ici.

svn branch create

Branches et SVN (suite)

svn branch switch

Branches et SVN (suite)

En ligne de commande (cf. source):

# svn list http://.../MyRepo
branch/
tags/
trunk/

Branches et SVN (suite)

# svn cp -m 'Making test branch' http://.../MyRepo/trunk http://.../MyRepo/branch/newBranch
...

Branches et SVN (suite)

# svn list http://.../MyRepo/branch
newBranch/

Branches et SVN (suite)

[source,shell]

svn merge http://…​/MyRepo/branch/newBranch .

=== {revisions}

[icon="{iconsdir}/tuxteacher.png"]
[NOTE]
====
. Pour ceux qui ont le support avec eux (ordi, tablette, portable) : trouvez un exemple de violation de la bonne pratique <<DRY>> dans ce support de cours (indice : mes codes {ruby} sont souvent écrits à l'arrache)
. Pourquoi les concepteurs de {papyrus} insistent-ils sur la qualité de leur documentation?
====


:leveloffset: 0

:numbered!:

[[Glossaire]]
== Glossaire

*Acronymes UML/SysML*

`{act}`:: Raccourcis pour Diagramme d'**ACT**ivité dans une cartouche {SysML}
`{bdd}`:: Raccourcis pour **B**lock **D**efinition **D**iagram dans une cartouche {SysML}
`{dc}`:: **D**iagramme de **C**lasse {UML}
`{dss}`:: **D**iagramme de **S**équence **S**ystème (un {seq} où seul le système dans sa globalité est représenté footnote:[Il ne s'agit pas d'un acronyme {SysML} à proprement parler mais nous l'utilisons beaucoup.])
`{ibd}`:: Raccourcis pour **I**nternal **B**lock **D**iagram dans une cartouche {SysML}
`{par}`:: Raccourcis pour **P**arametric Diagram dans une cartouche {SysML}
`{pkg}`:: Raccourcis pour **P**a**K**a**G**e Diagram dans une cartouche {SysML}
`{req}`:: Raccourcis pour **REQ**uirements Diagram dans une cartouche {SysML}
`{seq}`:: Raccourcis pour **SEQ**quence Diagram dans une cartouche {SysML}
`{stm}`:: Raccourcis pour **ST**ate **M**achine dans une cartouche {SysML}
`{uc}`:: Raccourcis pour **U**se **C**ase Diagram dans une cartouche {SysML}

*Définitions générales*


[NOTE]
.Ressources
=====================================================================
Les définitions ci-dessous sont regroupées à titre indicatif. Je vous invite
à consulter les sources suivantes :

- Glossaire du http://www.sei.cmu.edu/architecture/start/glossary[Software Engineering Institute]
- http://www.computer-dictionary-online.org/[IEEE Computer Dictionary Online]
- http://fr.wikipedia.org/[Wikipedia] – Version française
=====================================================================

[[CI]]CI::
	_**C**ontinuous **I**ntegration_ : (Intégration Continue) est un ensemble de pratiques utilisées en génie logiciel consistant à vérifier à chaque modification de code source que le résultat des modifications ne produit pas de régression dans l'application développée (source link:
	http://fr.wikipedia.org/wiki/Int%C3%A9gration_continue[ici]).

[[DRY]]DRY::
	_**D**on't **R**epeat **Y**ourself_ : Un bon principe qui veut qu'on évite de répéter des tâches manuelles (comme les tests) en utilisant plutôt des scripts et des programmes.
OMG::
	_**O**bject **M**anagement **G**roup_ : L'organisme international chargé des principales normes liés à l'objet (CORBA, UML, etc.).
[[TDD]]TDD::
	_**T**est **D**riven **D**evelopment_ : Développements dirigés par les tests. On écrit les tests avant d'écrire le code. On travaille son
	code tant que les tests ne passent pas.
TRL::
	_**T**echnology **R**eadiness **L**evel_ : Système de mesure employé par des agences gouvernementales américaines et par de nombreuses compagnies (et agences) mondiales afin d'évaluer le niveau de maturité d'une technologie (cf. http://fr.wikipedia.org/wiki/Technology_Readiness_Level[Wikipedia]).
[[STI2D]]STI2D::
	**S**ciences et **T**echnologies de l'**I**ndustrie et du **D**éveloppement **D**urable : série du baccarauléat qui met
	l'accent sur les technologies transversales et qui a introduit en 2011 l'enseignement de {sysml}.
SysML::
	_**Sys**tem **M**odeling **L**anguage_ (TM) : Le langage de modélisation de systèmes maintenu par l'{omg}.
UML::
	_**U**nified **M**odeling **L**anguage_ (TM) : Le langage de modélisation généraliste maintenu par l'{omg}.

[[refs]]
== Liens utiles

- Le site officiel d'{UML} : http://www.uml.org/
- Un site très bien fait sur {UML} : http://www.uml-sysml.org/

[[refs]]
== Références

Voici quelques références utiles.

- [[[ENS2013]]] L. Gendre et J.-M. Virely, SysML. Tutoriel du 13/06/2013. ENS Cachan.
- [[[FIO2012]]] Fiorèse S., Meinadier J., Découvrir et comprendre l’ingénierie système, AFIS 2012.
- [[[FMS]]] A. Moore, R. Steiner, S. Friedenthal, A Practical Guide to SysML, The MK/OMG Press, MK/OMG Press, 2011 (2nd edition).
- [[[Fejoz2013]]] Loïc Fejoz. [[SysML4STI2D]]SysML4STI2D, présentation de SysML en STI2D, 2004. Disponible http://fr.slideshare.net/REALTIMEATWORK/sysml4sti2d[ici].
- [[[Fowler2004]]] Martin Fowler. UML 2.0 INFORMATIQUE PROFESSIONNELLE, 2004.
- [[[HAS2012]]] Haskins C., SE Handbook Working Group, INCOSE Systems Engineering Handbook: Version 3.2.2, International Council on Systems Engineering, 2012.
- [[[Harmony]]] Bruce Powel Douglass. Real-Time Agility: The Harmony/ESW Method for Real-Time and Embedded Systems Development. Addison-Wesley Professional, 2009. ISBN-10: 0-321-54549-4
- [[[KAP2007]]] Kapurch S., NASA Systems Engineering Handbook, 2007 (http://ntrs.nasa.gov/archive/nasa/casi.ntrs.nasa.gov/20080008301_2008008500.pdf[pdf]).
- [[[MeDICIS]]] ENSI Bourges/PRiSM.
- [[[Modelio2012]]] Systems Engineering using Modelio, INCOSE 2012 Tool Vendor Challenge Case Study. Disponible  http://www.modeliosoft.com/en/component/docman/doc_download/360-white-paper-systems-engineering-using-modelio-incose-2012-symposiums-tvc-case-study-en.html[ici].
- [[[OMG2009]]] The Current State of Model Based Systems Engineering: Results from the OMG SysML Request for Information. Mary Bone and Robert Cloutier, 2009. Disponible http://www.omgsysml.org/SysML_2009_RFI_Response_Summary-bone-cloutier.pdf[ici].
- [[[REQ2012]]] Guide Bonnes Pratiques en Ingénierie des Exigences, AFIS 2012.
- [[[Roques2010]]] {prfc}. SysML par l'exemple - Un langage de modélisation pour systèmes complexes. Eyrolles. À obtenir http://www.numilog.com/LIVRES/FICHES/62775.Livre[ici].
- [[[SeeBook2012]]] Embedded Systems Analysis and Modeling with SysML, UML and AADL, F. Kordon, J. Hugues, A. Canals, A. Dohet, Wiley, 2013.
- [[[Sommerville1997]]] Ian Sommerville, Pete Sawyer. Requirements Engineering: A Good Practice Guide. Wiley, 1997.
- [[[Styles]]] Scott W. Ambler. The Elements of UML 2.0 Style. Cambridge University Press, 2005. ISBN: 0-521-61678-6
- [[[SysML]]] OMG. Systems modeling language version 1.3. Technical report, 2012. Available http://www.omg.org/spec/SysML/1.3/PDF[here].
- [[[Walsh1999]]] Norman Walsh & Leonard Muellner. DocBook - The Definitive Guide. O'Reilly & Associates. 1999. ISBN 1-56592-580-7.
- [[[TAOUP]]] Eric Steven Raymond. 'The Art of Unix Programming'. Addison-Wesley. ISBN 0-13-142901-9.
- [[[TestsIndustriels2009]]] Guide méthodologique de l'industrialisation et référentiel de bonnes pratiques. Disponible link:http://lifc.univ-fcomte.fr/test_indus/index.php?option=com_docman&task=doc_download&gid=36[ici].

== A propos de ce document...

**********************************************************************
Document généré par mailto:{email}[{author}] via {asciidoctorlink} (version +0.1.5+) de 'Dan Allen', lui même basé sur {asciidoc}.
Pour l'instant ce document est libre d'utilisation et géré par la 'Licence Creative Commons'.
image:{iconsdir}/88x31.png["Licence Creative
Commons",style="border-width:0",link="http://creativecommons.org/licenses/by-sa/3.0/"]
http://creativecommons.org/licenses/by-sa/3.0/[licence Creative Commons Paternité - Partage à l&#39;Identique 3.0 non transposé].
**********************************************************************